<!doctype html>
<html lang="en">
<head>
  <meta charset='utf-8'>
  <title>ulysses-js 1.4.0 | Documentation</title>
  <meta name='viewport' content='width=device-width,initial-scale=1'>
  <link href='assets/bass.css' rel='stylesheet'>
  <link href='assets/style.css' rel='stylesheet'>
  <link href='assets/github.css' rel='stylesheet'>
  <link href='assets/split.css' rel='stylesheet'>
</head>
<body class='documentation m0'>
    <div class='flex'>
      <div id='split-left' class='overflow-auto fs0 height-viewport-100'>
        <div class='py1 px2'>
          <h3 class='mb0 no-anchor'>ulysses-js</h3>
          <div class='mb1'><code>1.4.0</code></div>
          <input
            placeholder='Filter'
            id='filter-input'
            class='col12 block input'
            spellcheck='false'
            autocapitalize='off'
            autocorrect='off'
            type='text' />
          <div id='toc'>
            <ul class='list-reset h5 py1-ul'>
              
                
                <li><a
                  href='#ulysses'
                  class=" toggle-sibling">
                  Ulysses
                  <span class='icon'>▸</span>
                </a>
                
                <div class='toggle-target display-none'>
                  
                  
                    <ul class='list-reset py1-ul pl1'>
                      <li class='h5'><span>Instance members</span></li>
                      
                      <li><a
                        href='#ulyssescurrent'
                        class='regular pre-open'>
                        #current
                      </a></li>
                      
                      <li><a
                        href='#ulysseslength'
                        class='regular pre-open'>
                        #length
                      </a></li>
                      
                      <li><a
                        href='#ulyssesnext'
                        class='regular pre-open'>
                        #next
                      </a></li>
                      
                      <li><a
                        href='#ulyssesprevious'
                        class='regular pre-open'>
                        #previous
                      </a></li>
                      
                      <li><a
                        href='#ulyssesstep'
                        class='regular pre-open'>
                        #step
                      </a></li>
                      
                      <li><a
                        href='#ulysseson'
                        class='regular pre-open'>
                        #on
                      </a></li>
                      
                      <li><a
                        href='#ulyssesonce'
                        class='regular pre-open'>
                        #once
                      </a></li>
                      
                      <li><a
                        href='#ulyssesoff'
                        class='regular pre-open'>
                        #off
                      </a></li>
                      
                      <li><a
                        href='#ulyssestrigger'
                        class='regular pre-open'>
                        #trigger
                      </a></li>
                      
                      <li><a
                        href='#ulyssesuse'
                        class='regular pre-open'>
                        #use
                      </a></li>
                      
                      <li><a
                        href='#ulyssesdestroy'
                        class='regular pre-open'>
                        #destroy
                      </a></li>
                      
                    </ul>
                  
                  
                  
                </div>
                
                </li>
              
                
                <li><a
                  href='#examples'
                  class="h5 bold black caps">
                  Examples
                  
                </a>
                
                </li>
              
                
                <li><a
                  href='#events'
                  class="h5 bold black caps">
                  Events
                  
                </a>
                
                </li>
              
                
                <li><a
                  href='#built-in-actions'
                  class="h5 bold black caps toggle-sibling">
                  Built-in actions
                  <span class='icon'>▸</span>
                </a>
                
                <div class='toggle-target display-none'>
                  
                  <ul class='list-reset py1-ul pl1'>
                    <li class='h5'><span>Static members</span></li>
                    
                      <li><a
                        href='#flyto'
                        class='regular pre-open'>
                        .flyTo
                      </a></li>
                    
                      <li><a
                        href='#fitbounds'
                        class='regular pre-open'>
                        .fitBounds
                      </a></li>
                    
                      <li><a
                        href='#noop'
                        class='regular pre-open'>
                        .noop
                      </a></li>
                    
                    </ul>
                  
                  
                  
                  
                </div>
                
                </li>
              
                
                <li><a
                  href='#included-plugins'
                  class="h5 bold black caps toggle-sibling">
                  Included plugins
                  <span class='icon'>▸</span>
                </a>
                
                <div class='toggle-target display-none'>
                  
                  <ul class='list-reset py1-ul pl1'>
                    <li class='h5'><span>Static members</span></li>
                    
                      <li><a
                        href='#keys'
                        class='regular pre-open'>
                        .keys
                      </a></li>
                    
                      <li><a
                        href='#timer'
                        class='regular pre-open'>
                        .timer
                      </a></li>
                    
                      <li><a
                        href='#scroll'
                        class='regular pre-open'>
                        .scroll
                      </a></li>
                    
                    </ul>
                  
                  
                  
                  
                </div>
                
                </li>
              
                
                <li><a
                  href='#utilities'
                  class="h5 bold black caps toggle-sibling">
                  Utilities
                  <span class='icon'>▸</span>
                </a>
                
                <div class='toggle-target display-none'>
                  
                  <ul class='list-reset py1-ul pl1'>
                    <li class='h5'><span>Static members</span></li>
                    
                      <li><a
                        href='#getaction'
                        class='regular pre-open'>
                        .getAction
                      </a></li>
                    
                      <li><a
                        href='#extractoptions'
                        class='regular pre-open'>
                        .extractOptions
                      </a></li>
                    
                    </ul>
                  
                  
                  
                  
                </div>
                
                </li>
              
            </ul>
          </div>
          <div class='mt1 h6 quiet'>
            <a href='https://documentation.js.org/reading-documentation.html'>Need help reading this?</a>
          </div>
        </div>
      </div>
      <div id='split-right' class='relative overflow-auto height-viewport-100'>
        
          
          <section class='p2 mb2 clearfix bg-white minishadow'>

  
  <div class='clearfix'>
    
    <h3 class='fl m0' id='ulysses'>
      Ulysses
    </h3>
    
    
  </div>
  

  <p>Ulysses creates a narrative around geography by linking narrative steps to actions on a map.
Each step is a feature in a <a href="https://tools.ietf.org/html/rfc7946#section-3.3">GeoJSON feature collection</a>,
with a specific action defined as a property.</p>
<p>Actions are functions that change the map state -- panning, zooming, rotating, adding or removing layers --
anything you can do with the underlying map.</p>

    <div class='pre p1 fill-light mt0'>new Ulysses(map: mapboxgl.Map, steps: (<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a> | <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a>), actions: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>)</div>
  
  

  
  
  
  
  
  

  
    <div class='py1 quiet mt1 prose-big'>Parameters</div>
    <div class='prose'>
      
        <div class='space-bottom0'>
          <div>
            <span class='code bold'>map</span> <code class='quiet'>(mapboxgl.Map)</code>
	    The map we're controlling. For now, only mapbox is supported.

          </div>
          
        </div>
      
        <div class='space-bottom0'>
          <div>
            <span class='code bold'>steps</span> <code class='quiet'>((<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a> | <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a>))</code>
	    A 
<a href="https://tools.ietf.org/html/rfc7946#section-3.3">GeoJSON feature collection</a>
,
or an array of features, where each feature is a step in our story.

          </div>
          
        </div>
      
        <div class='space-bottom0'>
          <div>
            <span class='code bold'>actions</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>)</code>
	    An object containing action functions to be called for each feature.
This gets merged into default actions (
<code>flyTo</code>
, 
<code>fitBounds</code>
, 
<code>noop</code>
) so you can override those
defaults by adding new functions of the same name.

          </div>
          
        </div>
      
    </div>
  

  

  

  

  

  

  

  
    <div class='py1 quiet mt1 prose-big'>Instance Members</div>
    <div class="clearfix">
  
    <div class='border-bottom' id='ulyssescurrent'>
      <div class="clearfix small pointer toggle-sibling">
        <div class="py1 contain">
            <a class='icon pin-right py1 dark-link caret-right'>▸</a>
            <span class='code strong strong truncate'>current</span>
        </div>
      </div>
      <div class="clearfix display-none toggle-target">
        <section class='p2 mb2 clearfix bg-white minishadow'>

  

  <p>Get the current step number (zero-indexed)</p>

    <div class='pre p1 fill-light mt0'>current</div>
  
  

  
  
  
  
  
  

  

  

  
    
      <div class='py1 quiet mt1 prose-big'>Returns</div>
      <code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number">Number</a></code>:
        
      
    
  

  

  

  

  

  

  

  
</section>

      </div>
    </div>
  
    <div class='border-bottom' id='ulysseslength'>
      <div class="clearfix small pointer toggle-sibling">
        <div class="py1 contain">
            <a class='icon pin-right py1 dark-link caret-right'>▸</a>
            <span class='code strong strong truncate'>length</span>
        </div>
      </div>
      <div class="clearfix display-none toggle-target">
        <section class='p2 mb2 clearfix bg-white minishadow'>

  

  <p>Get the number fo steps in this story</p>

    <div class='pre p1 fill-light mt0'>length</div>
  
  

  
  
  
  
  
  

  

  

  
    
      <div class='py1 quiet mt1 prose-big'>Returns</div>
      <code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number">Number</a></code>:
        
      
    
  

  

  

  

  

  

  

  
</section>

      </div>
    </div>
  
    <div class='border-bottom' id='ulyssesnext'>
      <div class="clearfix small pointer toggle-sibling">
        <div class="py1 contain">
            <a class='icon pin-right py1 dark-link caret-right'>▸</a>
            <span class='code strong strong truncate'>next()</span>
        </div>
      </div>
      <div class="clearfix display-none toggle-target">
        <section class='p2 mb2 clearfix bg-white minishadow'>

  

  <p>Advance one step (unless we're at the end)</p>

    <div class='pre p1 fill-light mt0'>next()</div>
  
  

  
  
  
  
  
  

  

  

  

  

  

  

  

  

  

  
</section>

      </div>
    </div>
  
    <div class='border-bottom' id='ulyssesprevious'>
      <div class="clearfix small pointer toggle-sibling">
        <div class="py1 contain">
            <a class='icon pin-right py1 dark-link caret-right'>▸</a>
            <span class='code strong strong truncate'>previous()</span>
        </div>
      </div>
      <div class="clearfix display-none toggle-target">
        <section class='p2 mb2 clearfix bg-white minishadow'>

  

  <p>Go back a step (unless we're at the beginning)</p>

    <div class='pre p1 fill-light mt0'>previous()</div>
  
  

  
  
  
  
  
  

  

  

  

  

  

  

  

  

  

  
</section>

      </div>
    </div>
  
    <div class='border-bottom' id='ulyssesstep'>
      <div class="clearfix small pointer toggle-sibling">
        <div class="py1 contain">
            <a class='icon pin-right py1 dark-link caret-right'>▸</a>
            <span class='code strong strong truncate'>step(n)</span>
        </div>
      </div>
      <div class="clearfix display-none toggle-target">
        <section class='p2 mb2 clearfix bg-white minishadow'>

  

  <p>Go to step <code>n</code>, where <code>n</code> is a step number</p>

    <div class='pre p1 fill-light mt0'>step(n: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number">Number</a>)</div>
  
  

  
  
  
  
  
  

  
    <div class='py1 quiet mt1 prose-big'>Parameters</div>
    <div class='prose'>
      
        <div class='space-bottom0'>
          <div>
            <span class='code bold'>n</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number">Number</a>)</code>
	    Go to this step

          </div>
          
        </div>
      
    </div>
  

  

  

  

  

  

  

  

  

  
</section>

      </div>
    </div>
  
    <div class='border-bottom' id='ulysseson'>
      <div class="clearfix small pointer toggle-sibling">
        <div class="py1 contain">
            <a class='icon pin-right py1 dark-link caret-right'>▸</a>
            <span class='code strong strong truncate'>on(event, callback)</span>
        </div>
      </div>
      <div class="clearfix display-none toggle-target">
        <section class='p2 mb2 clearfix bg-white minishadow'>

  

  <p>Register a callback for a given event</p>

    <div class='pre p1 fill-light mt0'>on(event: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, callback: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">Function</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">Function</a></div>
  
  

  
  
  
  
  
  

  
    <div class='py1 quiet mt1 prose-big'>Parameters</div>
    <div class='prose'>
      
        <div class='space-bottom0'>
          <div>
            <span class='code bold'>event</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
	    
          </div>
          
        </div>
      
        <div class='space-bottom0'>
          <div>
            <span class='code bold'>callback</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">Function</a>)</code>
	    
          </div>
          
        </div>
      
    </div>
  

  

  
    
      <div class='py1 quiet mt1 prose-big'>Returns</div>
      <code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">Function</a></code>:
        unsubscribe function

      
    
  

  

  

  

  

  

  

  
</section>

      </div>
    </div>
  
    <div class='border-bottom' id='ulyssesonce'>
      <div class="clearfix small pointer toggle-sibling">
        <div class="py1 contain">
            <a class='icon pin-right py1 dark-link caret-right'>▸</a>
            <span class='code strong strong truncate'>once(event, callback)</span>
        </div>
      </div>
      <div class="clearfix display-none toggle-target">
        <section class='p2 mb2 clearfix bg-white minishadow'>

  

  <p>Register a callback for an event that only fires once</p>

    <div class='pre p1 fill-light mt0'>once(event: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, callback: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">Function</a>)</div>
  
  

  
  
  
  
  
  

  
    <div class='py1 quiet mt1 prose-big'>Parameters</div>
    <div class='prose'>
      
        <div class='space-bottom0'>
          <div>
            <span class='code bold'>event</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
	    
          </div>
          
        </div>
      
        <div class='space-bottom0'>
          <div>
            <span class='code bold'>callback</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">Function</a>)</code>
	    
          </div>
          
        </div>
      
    </div>
  

  

  

  

  

  

  

  

  

  
</section>

      </div>
    </div>
  
    <div class='border-bottom' id='ulyssesoff'>
      <div class="clearfix small pointer toggle-sibling">
        <div class="py1 contain">
            <a class='icon pin-right py1 dark-link caret-right'>▸</a>
            <span class='code strong strong truncate'>off(event, callback)</span>
        </div>
      </div>
      <div class="clearfix display-none toggle-target">
        <section class='p2 mb2 clearfix bg-white minishadow'>

  

  <p>Remove a callback for a given event. If callback is <code>undefined</code>, remove all callbacks for that event.</p>

    <div class='pre p1 fill-light mt0'>off(event: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, callback: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">Function</a>)</div>
  
  

  
  
  
  
  
  

  
    <div class='py1 quiet mt1 prose-big'>Parameters</div>
    <div class='prose'>
      
        <div class='space-bottom0'>
          <div>
            <span class='code bold'>event</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
	    
          </div>
          
        </div>
      
        <div class='space-bottom0'>
          <div>
            <span class='code bold'>callback</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">Function</a>)</code>
	    
          </div>
          
        </div>
      
    </div>
  

  

  

  

  

  

  

  

  

  
</section>

      </div>
    </div>
  
    <div class='border-bottom' id='ulyssestrigger'>
      <div class="clearfix small pointer toggle-sibling">
        <div class="py1 contain">
            <a class='icon pin-right py1 dark-link caret-right'>▸</a>
            <span class='code strong strong truncate'>trigger(event, detail)</span>
        </div>
      </div>
      <div class="clearfix display-none toggle-target">
        <section class='p2 mb2 clearfix bg-white minishadow'>

  

  <p>Fire callbacks for a given event. This is used internally but may be useful in actions and plugins.
The <code>detail</code> object is passed to callback functions.</p>

    <div class='pre p1 fill-light mt0'>trigger(event: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, detail: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>)</div>
  
  

  
  
  
  
  
  

  
    <div class='py1 quiet mt1 prose-big'>Parameters</div>
    <div class='prose'>
      
        <div class='space-bottom0'>
          <div>
            <span class='code bold'>event</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
	    
          </div>
          
        </div>
      
        <div class='space-bottom0'>
          <div>
            <span class='code bold'>detail</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>
            = <code>{}</code>)</code>
	    
          </div>
          
        </div>
      
    </div>
  

  

  

  

  

  

  

  

  

  
</section>

      </div>
    </div>
  
    <div class='border-bottom' id='ulyssesuse'>
      <div class="clearfix small pointer toggle-sibling">
        <div class="py1 contain">
            <a class='icon pin-right py1 dark-link caret-right'>▸</a>
            <span class='code strong strong truncate'>use(plugin)</span>
        </div>
      </div>
      <div class="clearfix display-none toggle-target">
        <section class='p2 mb2 clearfix bg-white minishadow'>

  

  <p>Apply a plugin function to this Ulysses instance</p>

    <div class='pre p1 fill-light mt0'>use(plugin: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">Function</a>): ThisType</div>
  
  

  
  
  
  
  
  

  
    <div class='py1 quiet mt1 prose-big'>Parameters</div>
    <div class='prose'>
      
        <div class='space-bottom0'>
          <div>
            <span class='code bold'>plugin</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">Function</a>)</code>
	    
          </div>
          
        </div>
      
    </div>
  

  

  
    
      <div class='py1 quiet mt1 prose-big'>Returns</div>
      <code>ThisType</code>:
        
      
    
  

  

  

  

  

  

  

  
</section>

      </div>
    </div>
  
    <div class='border-bottom' id='ulyssesdestroy'>
      <div class="clearfix small pointer toggle-sibling">
        <div class="py1 contain">
            <a class='icon pin-right py1 dark-link caret-right'>▸</a>
            <span class='code strong strong truncate'>destroy()</span>
        </div>
      </div>
      <div class="clearfix display-none toggle-target">
        <section class='p2 mb2 clearfix bg-white minishadow'>

  

  <p>Remove event listers and call plugin cleanup functions.
Triggers a "destroy" event with no data.</p>

    <div class='pre p1 fill-light mt0'>destroy()</div>
  
  

  
  
  
  
  
  

  

  

  

  

  

  

  

  

  

  
</section>

      </div>
    </div>
  
</div>

  

  

  
</section>

          
        
          
            <div class='keyline-top-not py2'><section class='py2 clearfix'>

  <h2 id='examples' class='mt0'>
    Examples
  </h2>

  
    <h3><a href="./examples/fires.html">The biggest fires of 2018</a></h3>
<p>Use the left and right arrow keys to move through the 10 largest wildfires for 2018.</p>
<p>Use numbers 0 through 9 to jump to a specific fire.</p>
<h3><a href="./examples/innout.html">Every In-N-Out</a></h3>
<p>Jump to a new In-N-Out location every few seconds. Hit the spacebar to stop and start.</p>
<p>Source: <a href="https://github.com/alltheplaces/alltheplaces">All the Places</a></p>
<h3><a href="./examples/odyssey.html">The Odyssey</a></h3>
<p>A scrollable story depicting the locations in Homer's Odyssey.</p>
<p>Source: <a href="https://www.arcgis.com/apps/MapTour/index.html?appid=4966f41a90c84a199a19057160322ee4">ESRI Story Map</a></p>

  
</section></div>
          
        
          
            <div class='keyline-top-not py2'><section class='py2 clearfix'>

  <h2 id='events' class='mt0'>
    Events
  </h2>

  
    <h3>Built-in events</h3>
<p>A <code>Ulysses</code> object triggers events as you move through steps, and you can listen to these to keep other parts of your interface in sync. Some steps receive additional data, which a callback can use.</p>
<p>Note that both the <code>next</code> and <code>previous</code> events fire <em>before</em> any actions are triggered. Use <code>step</code> for callbacks that should fire after the step completes.</p>
<p><strong>start</strong>: Fires before the first step. No additional data is included.</p>
<p><strong>next</strong> (<code>step</code>, <code>feature</code>): Fires each time <code>story.next()</code> is called, <em>before</em> actually moving to the next step. The included event has two members:</p>
<ul>
<li><code>step</code>: the index of <em>current</em> step (before changing)</li>
<li><code>feature</code>: the GeoJSON feature associated with the <em>current</em> step</li>
</ul>
<p><strong>previous</strong> (<code>step</code>, <code>feature</code>): Fires each time <code>story.previous()</code> is called, <em>before</em> actually moving to the previous step. The included event has two members:</p>
<ul>
<li><code>step</code>: the index of <em>current</em> step (before changing)</li>
<li><code>feature</code>: the GeoJSON feature associated with the <em>current</em> step</li>
</ul>
<p><strong>step</strong> (<code>step</code>, <code>feature</code>): Fires each time <code>story.step(n)</code> is called, <em>after</em> the step and associated action have fired (though not necessarily after all map updates have completed). The included event has two members:</p>
<ul>
<li><code>step</code>: the index of the <em>current</em> step (after changing)</li>
<li><code>feature</code>: the GeoJSON feature associated with the <em>current</em> step</li>
</ul>
<p><strong>end</strong>: Fires after the last step. No additional data is included.</p>
<p><strong>destroy</strong>: Fires when <code>story.destroy()</code> method is called, just before removing event listers and running plugin cleanup functions. No additional data is included.</p>
<h3>Custom events</h3>
<p>It's possible to define custom events. For example, an action might trigger a custom event to signal that it's finished, and a callback can listen for it.</p>
<pre class='hljs'><span class="hljs-keyword">let</span> success = <span class="hljs-literal">false</span>;

story.on(<span class="hljs-string">&quot;success&quot;</span>, <span class="hljs-function"><span class="hljs-params">e</span> =&gt;</span> {
	success = e.success;
});

story.trigger(<span class="hljs-string">&quot;success&quot;</span>, { <span class="hljs-attr">success</span>: <span class="hljs-literal">true</span> });</pre>

  
</section></div>
          
        
          
          <section class='p2 mb2 clearfix bg-white minishadow'>

  
  <div class='clearfix'>
    
    <h3 class='fl m0' id='built-in-actions'>
      Built-in actions
    </h3>
    
    
  </div>
  

  <p>These actions are included by default.
Override them by creating functions of the same name on your actions object.</p>

    <div class='pre p1 fill-light mt0'>Built-in actions</div>
  
  

  
  
  
  
  
  

  

  

  

  

  

  

  
    <div class='py1 quiet mt1 prose-big'>Static Members</div>
    <div class="clearfix">
  
    <div class='border-bottom' id='flyto'>
      <div class="clearfix small pointer toggle-sibling">
        <div class="py1 contain">
            <a class='icon pin-right py1 dark-link caret-right'>▸</a>
            <span class='code strong strong truncate'>flyTo(map, feature)</span>
        </div>
      </div>
      <div class="clearfix display-none toggle-target">
        <section class='p2 mb2 clearfix bg-white minishadow'>

  

  <p>flyTo wraps Mapbox's Map#flyTo method, extracting arguments from feature properties
and centering on this feature's geometry (which should be a point).</p>
<p>The following properties are extracted, converted to numbers
and passed to <a href="https://docs.mapbox.com/mapbox-gl-js/api/#map#flyto">Map#flyTo</a>:</p>
<ul>
<li><code>zoom</code></li>
<li><code>bearing</code></li>
<li><code>pitch</code></li>
<li><code>duration</code></li>
</ul>

    <div class='pre p1 fill-light mt0'>flyTo(map: mapboxgl.Map, feature: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>)</div>
  
  

  
  
  
  
  
  

  
    <div class='py1 quiet mt1 prose-big'>Parameters</div>
    <div class='prose'>
      
        <div class='space-bottom0'>
          <div>
            <span class='code bold'>map</span> <code class='quiet'>(mapboxgl.Map)</code>
	    The map attached to our current story

          </div>
          
        </div>
      
        <div class='space-bottom0'>
          <div>
            <span class='code bold'>feature</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>)</code>
	    The feature in view

          </div>
          
          <table class='mt1 mb2 fixed-table h5 col-12'>
            <colgroup>
              <col width='30%' />
              <col width='70%' />
            </colgroup>
            <thead>
              <tr class='bold fill-light'>
                <th>Name</th>
                <th>Description</th>
              </tr>
            </thead>
            <tbody class='mt1'>
              
                <tr>
  <td class='break-word'><span class='code bold'>feature.geometry</span> <code class='quiet'>any</code>
  </td>
  <td class='break-word'><span></span></td>
</tr>


              
                <tr>
  <td class='break-word'><span class='code bold'>feature.properties</span> <code class='quiet'>any</code>
  </td>
  <td class='break-word'><span></span></td>
</tr>


              
            </tbody>
          </table>
          
        </div>
      
    </div>
  

  

  

  

  

  

  

  

  

  
</section>

      </div>
    </div>
  
    <div class='border-bottom' id='fitbounds'>
      <div class="clearfix small pointer toggle-sibling">
        <div class="py1 contain">
            <a class='icon pin-right py1 dark-link caret-right'>▸</a>
            <span class='code strong strong truncate'>fitBounds(map, feature)</span>
        </div>
      </div>
      <div class="clearfix display-none toggle-target">
        <section class='p2 mb2 clearfix bg-white minishadow'>

  

  <p>fitBounds finds a bounding box for a feature and fits the map to it,
using <a href="https://docs.mapbox.com/mapbox-gl-js/api/#map#fitbounds">Map#fitBounds</a>.
If the feature has a bbox attribute, that is used. Otherwise, we calculate a bounding box
and use that.</p>
<p>The following properties are extracted, converted to numbers
and passed to <a href="https://docs.mapbox.com/mapbox-gl-js/api/#map#fitbounds">Map#fitBounds</a>:</p>
<ul>
<li><code>maxZoom</code></li>
<li><code>bearing</code></li>
<li><code>pitch</code></li>
<li><code>duration</code></li>
<li><code>padding</code> (single padding only)</li>
</ul>

    <div class='pre p1 fill-light mt0'>fitBounds(map: mapboxgl.Map, feature: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>)</div>
  
  

  
  
  
  
  
  

  
    <div class='py1 quiet mt1 prose-big'>Parameters</div>
    <div class='prose'>
      
        <div class='space-bottom0'>
          <div>
            <span class='code bold'>map</span> <code class='quiet'>(mapboxgl.Map)</code>
	    The map attached to our current story

          </div>
          
        </div>
      
        <div class='space-bottom0'>
          <div>
            <span class='code bold'>feature</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>)</code>
	    The feature in view

          </div>
          
        </div>
      
    </div>
  

  

  

  

  

  

  

  

  

  
</section>

      </div>
    </div>
  
    <div class='border-bottom' id='noop'>
      <div class="clearfix small pointer toggle-sibling">
        <div class="py1 contain">
            <a class='icon pin-right py1 dark-link caret-right'>▸</a>
            <span class='code strong strong truncate'>noop()</span>
        </div>
      </div>
      <div class="clearfix display-none toggle-target">
        <section class='p2 mb2 clearfix bg-white minishadow'>

  

  <p>noop is the best action because it wants nothing and gives nothing in return</p>

    <div class='pre p1 fill-light mt0'>noop()</div>
  
  

  
  
  
  
  
  

  

  

  

  

  

  

  

  

  

  
</section>

      </div>
    </div>
  
</div>

  

  

  

  
</section>

          
        
          
          <section class='p2 mb2 clearfix bg-white minishadow'>

  
  <div class='clearfix'>
    
    <h3 class='fl m0' id='included-plugins'>
      Included plugins
    </h3>
    
    
  </div>
  

  <p>A plugin is a function that adds functionality to a Ulysses instance. Add plugins in one of two ways:</p>
<pre class='hljs'><span class="hljs-comment">// when creating a story, use the `plugins` array</span>
<span class="hljs-keyword">const</span> story = <span class="hljs-keyword">new</span> Ulysses({ map, steps, <span class="hljs-attr">plugins</span>: [func, anotherFunc] });

<span class="hljs-comment">// later, with the `use()` method</span>
story.use(plugin);</pre>
<p>In each case, the plugin callable takes a <code>Ulysses</code> instance as its only argument. For plugins that take configuration, you can use a function that returns a function. Finally, the plugin function <em>may</em> return a cleanup function, which will be called when a Ulysses instance is destroyed.</p>
<p>Here's an example plugin that adds keyboad controls:</p>
<pre class='hljs'><span class="hljs-keyword">export</span> <span class="hljs-keyword">default</span> <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">keys</span>(<span class="hljs-params">{ previous = <span class="hljs-string">&quot;ArrowLeft&quot;</span>, next = <span class="hljs-string">&quot;ArrowRight&quot;</span> } = {}</span>) </span>{
	<span class="hljs-keyword">return</span> <span class="hljs-function"><span class="hljs-params">story</span> =&gt;</span> {
		<span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">keydown</span>(<span class="hljs-params">{ key }</span>) </span>{
			<span class="hljs-keyword">if</span> (key === previous) {
				story.previous();
			}

			<span class="hljs-keyword">if</span> (key === next) {
				story.next();
			}

			<span class="hljs-keyword">if</span> (key.match(<span class="hljs-regexp">/\d{1}/</span>)) {
				story.step(+e.key);
			}
		}

		<span class="hljs-built_in">window</span>.addEventListener(<span class="hljs-string">&quot;keydown&quot;</span>, keydown);

		<span class="hljs-comment">// on destroy</span>
		<span class="hljs-keyword">return</span> <span class="hljs-function">() =&gt;</span> {
			<span class="hljs-built_in">window</span>.removeEventListener(<span class="hljs-string">&quot;keydown&quot;</span>, keydown);
		};
	};
}

<span class="hljs-comment">// later</span>
story.use(keys());

<span class="hljs-comment">// when we&#x27;re done, this will remove the event listener</span>
story.destroy();</pre>
<p>The first function -- <code>keys()</code> -- is called to initialize the plugin and returns a function. That function is called with our <code>Ulysses</code> instance. When the story is eventually destroyed (for example, when routing to a new URL in a single-page application), the final cleanup function will remove event listers on the <code>window</code>.</p>

    <div class='pre p1 fill-light mt0'>Included plugins</div>
  
  

  
  
  
  
  
  

  

  

  

  

  

  

  
    <div class='py1 quiet mt1 prose-big'>Static Members</div>
    <div class="clearfix">
  
    <div class='border-bottom' id='keys'>
      <div class="clearfix small pointer toggle-sibling">
        <div class="py1 contain">
            <a class='icon pin-right py1 dark-link caret-right'>▸</a>
            <span class='code strong strong truncate'>keys(options)</span>
        </div>
      </div>
      <div class="clearfix display-none toggle-target">
        <section class='p2 mb2 clearfix bg-white minishadow'>

  

  <p>Add keyboard controls to a story. By default, this adds listeners for the
left and right keys, stepping backward and forward, respectively. Using the
numeric keys 0 - 9 will go to those steps.</p>
<p>Usage:</p>
<pre class='hljs'><span class="hljs-keyword">import</span> keys <span class="hljs-keyword">from</span> <span class="hljs-string">&quot;ulysses/plugins/keys.mjs&quot;</span>

story.use(keys({ <span class="hljs-attr">previous</span>: <span class="hljs-string">&quot;ArrowLeft&quot;</span>, <span class="hljs-attr">next</span>: <span class="hljs-string">&quot;ArrowRight&quot;</span> }))</pre>
<p>See <a href="./examples/fires.html">Every fire in 2018</a></p>

    <div class='pre p1 fill-light mt0'>keys(options: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>)</div>
  
  

  
  
  
  
  
  

  
    <div class='py1 quiet mt1 prose-big'>Parameters</div>
    <div class='prose'>
      
        <div class='space-bottom0'>
          <div>
            <span class='code bold'>options</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>
            = <code>{}</code>)</code>
	    [{ previous = "ArrowLeft", next = "ArrowRight" }={}]

          </div>
          
          <table class='mt1 mb2 fixed-table h5 col-12'>
            <colgroup>
              <col width='30%' />
              <col width='70%' />
            </colgroup>
            <thead>
              <tr class='bold fill-light'>
                <th>Name</th>
                <th>Description</th>
              </tr>
            </thead>
            <tbody class='mt1'>
              
                <tr>
  <td class='break-word'><span class='code bold'>options.previous</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code>
  
    (default <code>&quot;ArrowLeft&quot;</code>)
  </td>
  <td class='break-word'><span>Use this key to go to the previous step. Default: 
<code>ArrowLeft</code>
</span></td>
</tr>


              
                <tr>
  <td class='break-word'><span class='code bold'>options.next</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code>
  
    (default <code>&quot;ArrowRight&quot;</code>)
  </td>
  <td class='break-word'><span>Use this key to go to the next step. Default: 
<code>ArrowRight</code>
</span></td>
</tr>


              
            </tbody>
          </table>
          
        </div>
      
    </div>
  

  

  

  

  

  

  

  

  

  
</section>

      </div>
    </div>
  
    <div class='border-bottom' id='timer'>
      <div class="clearfix small pointer toggle-sibling">
        <div class="py1 contain">
            <a class='icon pin-right py1 dark-link caret-right'>▸</a>
            <span class='code strong strong truncate'>timer(options)</span>
        </div>
      </div>
      <div class="clearfix display-none toggle-target">
        <section class='p2 mb2 clearfix bg-white minishadow'>

  

  <p>Add a timer that advances the map every <code>duration</code> seconds.</p>
<p>Usage:</p>
<pre class='hljs'><span class="hljs-keyword">import</span> timer <span class="hljs-keyword">from</span> <span class="hljs-string">&quot;ulysses/plugins/timer.mjs&quot;</span>

story.use(timer({ <span class="hljs-attr">duration</span>: <span class="hljs-number">5000</span>, <span class="hljs-attr">toggle</span>: <span class="hljs-string">&quot;Space&quot;</span>, <span class="hljs-attr">start</span>: <span class="hljs-literal">true</span> }))</pre>
<p>This plugin adds additional methods to a Ulysses instance:</p>
<ul>
<li><code>Ulysses#start()</code> - Start the timer</li>
<li><code>Ulysses#stop()</code> - Stop the timer</li>
<li><code>Ulysses#toggle()</code> - Stop or start, depending on current state</li>
</ul>
<p>Each of these emits an event -- <code>timer.start</code>, <code>timer.stop</code>, <code>timer.toggle</code> --
that can be used to coordinate other actions.</p>

    <div class='pre p1 fill-light mt0'>timer(options: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>)</div>
  
  

  
  
  
  
  
  

  
    <div class='py1 quiet mt1 prose-big'>Parameters</div>
    <div class='prose'>
      
        <div class='space-bottom0'>
          <div>
            <span class='code bold'>options</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>
            = <code>{}</code>)</code>
	    [{ duration, toggle = "Space" }={}]

          </div>
          
          <table class='mt1 mb2 fixed-table h5 col-12'>
            <colgroup>
              <col width='30%' />
              <col width='70%' />
            </colgroup>
            <thead>
              <tr class='bold fill-light'>
                <th>Name</th>
                <th>Description</th>
              </tr>
            </thead>
            <tbody class='mt1'>
              
                <tr>
  <td class='break-word'><span class='code bold'>options.duration</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number">Number</a></code>
  
    (default <code>5000</code>)
  </td>
  <td class='break-word'><span>Time between steps, in milliseconds (default: 5000)
</span></td>
</tr>


              
                <tr>
  <td class='break-word'><span class='code bold'>options.toggle</span> <code class='quiet'>Space</code>
  
    (default <code>&quot;Space&quot;</code>)
  </td>
  <td class='break-word'><span>Key to toggle starting and stopping the timer (default: 
<code>"Space"</code>
)
</span></td>
</tr>


              
                <tr>
  <td class='break-word'><span class='code bold'>options.start</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">Boolean</a></code>
  
    (default <code>true</code>)
  </td>
  <td class='break-word'><span>Start the timer immediately. If false, call 
<code>story.start()</code>
 to begin.
</span></td>
</tr>


              
            </tbody>
          </table>
          
        </div>
      
    </div>
  

  

  

  

  

  

  

  

  

  
</section>

      </div>
    </div>
  
    <div class='border-bottom' id='scroll'>
      <div class="clearfix small pointer toggle-sibling">
        <div class="py1 contain">
            <a class='icon pin-right py1 dark-link caret-right'>▸</a>
            <span class='code strong strong truncate'>scroll(options)</span>
        </div>
      </div>
      <div class="clearfix display-none toggle-target">
        <section class='p2 mb2 clearfix bg-white minishadow'>

  

  <p>Add scroll interaction to a Ulysses story using scrollama.
As each element scrolls into view, the story will trigger a step.</p>
<p>Any options given during initialization are passed through to scrollama.
See <a href="https://github.com/russellgoldenberg/scrollama#scrollamasetupoptions">scrollama's API documentation</a>
for a full list of available options.</p>
<p>Usage:</p>
<pre class='hljs'><span class="hljs-keyword">import</span> scroll <span class="hljs-keyword">from</span> <span class="hljs-string">&quot;ulysses/plugins/scroll.mjs&quot;</span>

story.use(scroll({ <span class="hljs-attr">step</span>: <span class="hljs-string">&quot;.step&quot;</span> }))</pre>

    <div class='pre p1 fill-light mt0'>scroll(options: scrollama.ScrollamaOptions)</div>
  
  

  
  
  
  
  
  

  
    <div class='py1 quiet mt1 prose-big'>Parameters</div>
    <div class='prose'>
      
        <div class='space-bottom0'>
          <div>
            <span class='code bold'>options</span> <code class='quiet'>(scrollama.ScrollamaOptions
            = <code>{}</code>)</code>
	    
          </div>
          
        </div>
      
    </div>
  

  

  

  

  

  

  

  

  

  
</section>

      </div>
    </div>
  
</div>

  

  

  

  
</section>

          
        
          
          <section class='p2 mb2 clearfix bg-white minishadow'>

  
  <div class='clearfix'>
    
    <h3 class='fl m0' id='utilities'>
      Utilities
    </h3>
    
    
  </div>
  

  <p>These might help when defining your own actions.</p>

    <div class='pre p1 fill-light mt0'>Utilities</div>
  
  

  
  
  
  
  
  

  

  

  

  

  

  

  
    <div class='py1 quiet mt1 prose-big'>Static Members</div>
    <div class="clearfix">
  
    <div class='border-bottom' id='getaction'>
      <div class="clearfix small pointer toggle-sibling">
        <div class="py1 contain">
            <a class='icon pin-right py1 dark-link caret-right'>▸</a>
            <span class='code strong strong truncate'>getAction(feature, actions)</span>
        </div>
      </div>
      <div class="clearfix display-none toggle-target">
        <section class='p2 mb2 clearfix bg-white minishadow'>

  

  <p>Get the action function based on feature properties</p>
<p>First, check for an <code>action</code> property that matches a member of actions.
Next, try a default action.</p>
<ul>
<li>if there's a bounding box, <code>fitBounds</code></li>
<li>if it's a point, a point, <code>flyTo</code></li>
<li>if it's a polygon (or anything else, really), find a bounding box and call <code>fitBounds</code></li>
</ul>

    <div class='pre p1 fill-light mt0'>getAction(feature: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>, actions: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">function</a></div>
  
  

  
  
  
  
  
  

  
    <div class='py1 quiet mt1 prose-big'>Parameters</div>
    <div class='prose'>
      
        <div class='space-bottom0'>
          <div>
            <span class='code bold'>feature</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>
            = <code>{}</code>)</code>
	    a single 
<a href="https://tools.ietf.org/html/rfc7946#section-3.2">geojson feature</a>
,
usually the one in view

          </div>
          
        </div>
      
        <div class='space-bottom0'>
          <div>
            <span class='code bold'>actions</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>
            = <code>{}</code>)</code>
	    an object with defined actions to use. Each action is a function that takes
a map and the current feature in view.

          </div>
          
        </div>
      
    </div>
  

  

  
    
      <div class='py1 quiet mt1 prose-big'>Returns</div>
      <code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">function</a></code>:
        with the signature 
<code>action(map, feature): void</code>

      
    
  

  

  

  

  

  

  

  
</section>

      </div>
    </div>
  
    <div class='border-bottom' id='extractoptions'>
      <div class="clearfix small pointer toggle-sibling">
        <div class="py1 contain">
            <a class='icon pin-right py1 dark-link caret-right'>▸</a>
            <span class='code strong strong truncate'>extractOptions(properties, keys, cast)</span>
        </div>
      </div>
      <div class="clearfix display-none toggle-target">
        <section class='p2 mb2 clearfix bg-white minishadow'>

  

  <p>Extract options named in keys from properties and cast to type</p>

    <div class='pre p1 fill-light mt0'>extractOptions(properties: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>, keys: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a>&#x3C;<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>>, cast: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">function</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">object</a></div>
  
  

  
  
  
  
  
  

  
    <div class='py1 quiet mt1 prose-big'>Parameters</div>
    <div class='prose'>
      
        <div class='space-bottom0'>
          <div>
            <span class='code bold'>properties</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>)</code>
	    A properties object from a feature from which to extract values

          </div>
          
        </div>
      
        <div class='space-bottom0'>
          <div>
            <span class='code bold'>keys</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a>&#x3C;<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>>
            = <code>[]</code>)</code>
	    A list of keys to extract

          </div>
          
        </div>
      
        <div class='space-bottom0'>
          <div>
            <span class='code bold'>cast</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">function</a>
            = <code>id</code>)</code>
	    A function to convert keys to a different type, ie 
<code>Number</code>

          </div>
          
        </div>
      
    </div>
  

  

  
    
      <div class='py1 quiet mt1 prose-big'>Returns</div>
      <code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">object</a></code>:
        An options object, with values converted by 
<code>cast</code>

      
    
  

  

  

  

  

  

  

  
</section>

      </div>
    </div>
  
</div>

  

  

  

  
</section>

          
        
      </div>
    </div>
  <script src='assets/anchor.js'></script>
  <script src='assets/split.js'></script>
  <script src='assets/site.js'></script>
</body>
</html>
